跳到主要内容

Codex SDK

Codex SDK 适合把 Codex 能力嵌入自己的 Node.js、TypeScript 或后台系统中。它比 shell 调用更容易管理线程、事件、输出和错误。

官方内容整理​

  • SDK 面向程序化集成，适合自动化服务、内部工具、研发平台和自定义 agent 工作流。
  • 相比直接调用 CLI，SDK 更适合在应用代码中启动 Codex 任务、监听事件、处理输出、管理错误和记录状态。
  • SDK 可以让你把 Codex 放入自己的队列、调度系统、审批流、审计系统和用户界面。
  • 对一次性 CI 或简单脚本，非交互模式通常足够；对长期维护的产品集成，SDK 更稳定。
  • SDK 与 Codex 的线程、turn、事件和最终输出模型相匹配，能更细粒度地处理运行过程。
  • 选择 SDK 时，需要同时考虑认证、工作目录、权限模式、模型配置、日志、重试和用户可见状态。

实践补充​

SDK 的核心价值不是“少写一行命令”，而是让 Codex 成为你系统里的一个可观测组件。你可以把任务状态放进数据库，把事件推到 WebSocket，把最终结果放进 PR 评论，把失败原因进入告警系统。

如果你的需求只是定时跑一个提示词，先用 codex exec。当你需要多用户、状态管理、任务队列、可视化进度、权限隔离和审计时，再升级到 SDK。

推荐工作流​

  1. 先定义任务对象：用户、项目、工作目录、prompt、权限、输出契约。
  2. 用 SDK 启动任务并监听事件，把状态写入数据库或队列。
  3. 对每个任务保存最终消息、结构化结果、diff、日志位置和错误原因。
  4. 在 UI 中展示进度、需要人工确认的问题和最终结果。
  5. 为长任务建立取消、重试、恢复和超时策略。

示例提示词​

请帮我设计一个基于 Codex SDK 的内部代码评审服务。要求包含任务表结构、状态流转、事件处理、权限模式、失败重试、最终输出 schema 和 UI 展示字段。
请把这个现有的 shell 版 codex exec 自动化迁移成 SDK 集成方案。说明哪些参数、事件、日志和错误处理需要在应用层接管。